HyperLib 1997 Winter - Disc 1/HYPERLIB-1997-Winter-CD1.ISO.7z/HYPERLIB-1997-Winter-CD1.ISO/オンラインウェア/UTIL/ES 1.2 Package.sit/ES 1.2 Package/Developer’s toolkit/Headers/ExtensionsStrip.p

Text File | 1995-12-09 | 16KB | 381 lines

{
     File:        ExtensionsStrip.p

     Contains:    Extensions Strip Specific Interfaces for Control Strip modules.

     Version:    Technology:    System 7.1+ (System 7.5+ preferred)
                 Package:    Extensions Strip 1.2

     Copyright:    ｩ 1995 by Ammon Skidmore, Skidperfect Software Inc.
                 All rights reserved.

     Bugs?:        If you find a problem, have a criticism or comment with this
                 file, please inform the author at the following address:
                     Internet:    [e-mail]
}

{$IFC UNDEFINED UsingIncludes}
{$SETC UsingIncludes := 0}
{$ENDC}

{$IFC NOT UsingIncludes}
 UNIT ExtensionsStrip;
 INTERFACE
{$ENDC}

{$IFC UNDEFINED __EXTENSIONSSTRIP__}
{$SETC __EXTENSIONSSTRIP__ := 1}

{$I+}
{$SETC ExtensionsStripIncludes := UsingIncludes}
{$SETC UsingIncludes := 1}


{$IFC UNDEFINED __CONTROLSTRIP__}
{$I ControlStrip.p}
{$ENDC}

{$IFC UNDEFINED __APPLEEVENTS__}
{$I AppleEvents.p}
{$ENDC}


{$PUSH}
{$ALIGN MAC68K}
{$LibExport+}

{******************************************************************************************

    Special Extensions Strip selector calls to modules.

******************************************************************************************}
CONST
    sdevInAppContext            = 2000;    {   called only once after the module specifically        }
                                        {   requested to be executed from inside Extension        }
                                        {   Strip's context. NB: you can return the special        }
                                        {   result values.                                        }
                                        {}
    sdevInterceptedEvent        = 2001;    {    if the module returned the sdevInterceptAllEvents    }
                                        {   flag in its features, then this selector            }
                                        {   will get called before _each_ event is processed    }
                                        {   by Extensions Strip.  Meant to be used with            }
                                        {   _SBGetCurrentEvent so each event can be looked at,    }
                                        {   and modified if necessary (to prevent passing.)        }
                                        {   NB: you can return the special result values.        }
                                        {}
    sdevDragAccept                = 2002;    {    return 0 if you accept the current drag, and        }
                                        {   1 if you do not.  Modules that do not have any        }
                                        {   drag handlers will never get this called.            }
                                        {   NB: sdevDragAccept is only called from within        }
                                        {   Extensions Strip's dragTrackingInWindow.  So it        }
                                        {   is recommended to only check if you accept the drag    }
                                        {   from within your dragTrackingEnterWindow, and then    }
                                        {   set a global var that you can pass onto ES.            }
                                        {}
    sdevEventMask                = 2003;    {    if the module returned the sdevInterceptAllEvents    }
                                        {   flag in its features, this selector will get        }
                                        {   called to find the event mask to use.  Return your    }
                                        {   mask as the result value of the sdev call.            }
                                        {   sdevEventMask is called once upon initialization,    }
                                        {   and every time sdevFeaturesChange is requested.        }


{******************************************************************************************

    Features supported by the module.  If a bit is set, it means that feature is supported.

    Tip: if you clear sdevWantMouseClicks and set sdevDontAutoTrack, your module
    will receive clicks and Extensions Strip (plus Desktop Strip) will not
    auto-hilite your module.

******************************************************************************************}
    sdevHasDragHandlers            = 31;    {    module has installed a drag tracking and/or            }
                                        {   receive handler in the Strip window.                }
                                        {}
    sdevDontPeriodicTickle        = 30;    {    module does not require any idle time so            }
                                        {   by setting this bit it will never get                }
                                        {   called with the sdevPeriodicTickle                     }
                                        {   selector.  Note that you can set this along            }
                                        {   with the sdevInterceptAllEvents bit (if you want)    }
                                        {   and sdevInterceptedEvent will still get called.        }
                                        {   So be nice and set this to help speed up idle        }
                                        {   time processing.                                    }
                                        {}
    sdevInterceptAllEvents        = 29;    {    module wants to be executed before each                }
                                        {   event passes through Extension Strip's                }
                                        {   jGNE filter.  Because the module is allowed            }
                                        {   to modify every event, there is no more need        }
                                        {   for modules, such as Terminator Strip, to            }
                                        {   install their own jGNE filters!                        }
                                        {   NB: You need to return an event mask when your        }
                                        {   module is called by the sdevEventMask selector.        }


{******************************************************************************************

    Special result values returned by the sdevPeriodicTickle and sdevMouseClick selectors.
    If a bit is set, the module can request that a specific function is performed by
    the Control Strip.  All undefined bits should be set to zero.

    Note: these values can also be returned by the sdevInAppContext and
    sdevInterceptedEvent selectors.

******************************************************************************************}
    sdevQueueModule                = 31;    {    module needs to be executed from within                }
                                        {   Extension Strip's context: useful for                }
                                        {   things like sending AppleEvents or                    }
                                        {   creating and tracking new drags.                    }
                                        {}
    sdevFeaturesChange            = 30;    {    module wants to change its feature flags. Useful    }
                                        {   for changing clickable state of the module and        }
                                        {   for locking/unlocking the sdev code.                }

{******************************************************************************************

    miscellaneous

******************************************************************************************}
    kModuleFolderType                = 'sdev';    { FindFolder type for the root folder        }
    kModuleDisabledFolderType        = 'sdeD';    { FindFolder type for the disabled            }
                                                { root folder (place to put inactive        }
                                                { modules that you don't want deleted.)        }
    sdevTypeCodePPC                    = 'Sdev';    { resource type for module's PPC code        }

    gestaltExtensionsStripAttr        = 'CsEs';    {returns Extensions Strip's attributes.        }
    { currently returned bits from gestaltExtensionsStripAttr: }
    gestaltExtensionsStripExists    = 0;        {Extensions Strip is currently launched        }
    gestaltSupportsFontTraps        = 1;        { The new font traps of Control Strip 1.2    }
                                                { are supported.  ES 1.0 incorrectly gave    }
                                                { Control Strip's font trap gestalt bit.    }
    gestaltHasSBResolveAliasFile    = 2;        { ES contains the new alias resolving trap.    }
                                                { This bit also signifies that ES can only    }
                                                { be run as a regular application.            }

    gestaltDesktopStripAttr            = 'CsWT';    { returns the Desktop Strip program            }
                                                { attributes which are supported by            }
                                                { Extensions Strip.  See Desktop Strip's    }
                                                { docs for details about the bits            }

TYPE
    ModuleReference = LONGINT;


    SBQueueProcPtr = ProcPtr;  { PROCEDURE SBQueue(refCon: LONGINT); }
    SBQueueUPP = UniversalProcPtr;

CONST
    uppQueueProcProcInfo =  $000000C0; { PROCEDURE (4 byte param); }

FUNCTION NewSBQueueProcProc(userRoutine: SBQueueProcPtr): SBQueueUPP;
    {$IFC NOT GENERATINGCFM }
    INLINE $2E9F;
    {$ENDC}

{******************************************************************************************

    Control Strip trap calls

******************************************************************************************}

{                                                                                 }
{ All routines are documented as to whether the Extensions Strip implementation  }
{ of them they may move memory.  You can trust that a routine that says it         }
{ will not move memory in this version, will not move memory in future versions. }
{ Note though, that some Universal Control Strip traps may move memory under     }
{ Control/Desktop Strip but not in Extensions Strip (such as                     }
{ _SBIsControlStripVisible and _SBShowHideControlStrip.)                         }
{                                                                                 }

{ ===================================================== }
{ =========== Universal Control Strip traps =========== }
{ ===================================================== }
{
'Yes' = May move memory!
'No'  = Will not move memory.
'unimplemented'    = Trap not supported by Extensions Strip when this header file
                was released.  Check the Control Strip gestalt features to
                determine if/when Extensions Strip supports these traps.

SBIsControlStripVisible        no
SBShowHideControlStrip        no
SBSafeToAccessStartupDisk    no
SBOpenModuleResourceFile    yes
SBLoadPreferences            yes
SBSavePreferences            yes
SBGetDetachedIndString        no
SBGetDetachIconSuite        yes
SBTrackPopupMenu            yes
SBTrackSlider                yes
SBShowHelpString            yes
SBGetBarGraphWidth            no
SBDrawBarGraph                yes
SBModalDialogInContext        yes

Control Strip 1.2 and later
---------------------------
SBGetControlStripFontID        no
SBSetControlStripFontID        no
SBGetControlStripFontSize    no
SBSetControlStripFontSize    no
SBGetShowHideHotKey            unimplemented
SBSetShowHideHotKey            unimplemented
SBIsShowHideHotKeyEnabled    unimplemented
SBEnableShowHideHotKey        unimplemented
}

{ ===================================================== }
{ ========== Extensions Strip specific traps ========== }
{ ===================================================== }

{ Strip Window Utilities }

    { returns: true = vertical; false = horizontal }
    {}        { Will not move memory. }
FUNCTION SBIsControlStripVertical(stripPort: WindowRef): BOOLEAN;
    {$IFC NOT GENERATINGCFM}
    INLINE $70FF, $AAF2;
    {$ENDC}

    { returns pixel depth of the monitor this Strip window is in (always a power of 2) }
    {}        { Will not move memory. }
FUNCTION SBGetControlStripDepth(stripPort: WindowRef): INTEGER;
    {$IFC NOT GENERATINGCFM}
    INLINE $70FE, $AAF2;
    {$ENDC}

    { returns the current normal back color of this Strip window }
    {}        { Will not move memory. }
PROCEDURE SBGetStripBackColor(VAR color: RGBColor; stripPort: WindowRef);
    {$IFC NOT GENERATINGCFM}
    INLINE $70FD, $AAF2;
    {$ENDC}

    { returns the current back color of this Strip window when a module is selected }
    {}        { Will not move memory. }
PROCEDURE SBGetStripSelectedColor(VAR color: RGBColor; stripPort: WindowRef);
    {$IFC NOT GENERATINGCFM}
    INLINE $70FC, $AAF2;
    {$ENDC}

{ Module Utilities }

    { returns a reference number that all of the Module Utilities need                }
        { NB: since SBGetMyReferenceNum can ONLY be called from sdevInitModule,        }
        {   you should save its value into your globals if you are going to use        }
        {   one of the Module Utilities later, such as inside a tracking handler.    }
    { Also, the reference number will always be non-zero. }
    {}        { Will not move memory. }
FUNCTION SBGetMyReferenceNum: ModuleReference;
    {$IFC NOT GENERATINGCFM}
    INLINE $70FB, $AAF2;
    {$ENDC}

    { total window space taken up by a module.  Useful for drag-n-drop calculations }
    { note that this rect will always be larger than the module's statusRect. }
    {}        { Will not move memory. }
PROCEDURE SBGetTotalModuleBounds(VAR bounds: Rect; stripPort: WindowRef; moduleRefNum: ModuleReference);
    {$IFC NOT GENERATINGCFM}
    INLINE $70FA, $AAF2;
    {$ENDC}

    { returns the statusRect of the module.  Very useful for drag-n-drop routines }
    { because you no longer have to constantly set a global rectangle variable to }
    { hold the current location of the module in the Strip window. }
    {}        { Will not move memory. }
PROCEDURE SBGetModuleBounds(VAR bounds: Rect; moduleRefNum: ModuleReference);
    {$IFC NOT GENERATINGCFM}
    INLINE $70F9, $AAF2;
    {$ENDC}

{ Miscellaneous Utilities }

    { runs this (locked!) piece of code once within Extensions Strip's context.        }
    { PPC modules must pass a valid routine descriptor to this function.  Since        }
    { the descriptor will not be disposed of after the code has executed, I would    }
    { recommend creating the descriptor (NewSBQueueProcProc) when sdevInitModule    }
    { is called and disposing it upon sdevCloseModule.                                }
    { A non-zero result code means that the UPP could not be queued (memory error).    }
    {}        { May move memory! }
FUNCTION SBQueueCode(theProc: SBQueueUPP; refCon: LONGINT): OSErr;
    {$IFC NOT GENERATINGCFM}
    INLINE $70F8, $AAF2;
    {$ENDC}

    { sends the specified Apple Event within Extensions Strip's context to insure        }
    { safe sending rather than trusting that the front application is AE aware.            }
    { _SBSimpleAESend acts just like _AESend in that the AppleEvent you give to it        }
    { must still be disposed of afterward by your code to free up memory (even            }
    { though the event hasn't actually been sent yet.)                                    }
    {}
    { _SBSimpleAESend is meant to be an easy way to send simple events.  If you            }
    { need to check the reply AppleEvent or the _AESend error, ect., you should queue    }
    { your code (with _SBQueueCode or by having your module return 'sdevQueueModule')    }
    { and send the Apple Event yourself.  The result returned by _SBSimpleAESend        }
    { is only non-zero if an error occured while queueing the event for later sending.    }
    {}
    { Also, if an error does occur when Extensions Strip sends your AppleEvent, the        }
    { user will be notified with a dialog that _AESend failed.                            }
    {}
    { Here are the parameters I give to _AESend.  They are basic enough for most        }
    { kinds of Apple Events that modules send, hence the name _SBSimpleAESend.            }
    { err := AESend(theAppleEvent, reply,                 your specified AppleEvent        }
    {                                                    { and a dummy reply descriptor    }
    {            kAENoReply + kAEAlwaysInteract + kAECanSwitchLayer,     send mode        }
    {            kAENormalPriority,                                     send priority    }
    {            kAEDefaultTimeout,                                     time out            }
    {            nil,                                                 idleProc
    {            nil);                                                 filterProc
    {}        { May move memory! }
FUNCTION SBSimpleAESend({CONST}VAR theAppleEvent: AppleEvent): OSErr;
    {$IFC NOT GENERATINGCFM}
    INLINE $70F7, $AAF2;
    {$ENDC}


    { returns a pointer to the current event being processed.  Modififations to        }
    { the data in this pointer WILL take effect as the event gets passed along        }
    { to the other processes and jGNE filters further on in the chain.  Although    }
    { a module can use this function at any time, it is really meant to be called    }
    { within the sdevInterceptedEvent selector because this is where a module can    }
    { deny other modules the proper processing of the event (such as in the case    }
    { of a keyDown.)  Another good use for SBGetCurrentEvent() is to find the exact    }
    { point where a mouseDown occured if you have a queue of clickable objects.        }
    {}        { Will not move memory. }
TYPE
    EventRecordPtr = ^EventRecord;
FUNCTION SBGetCurrentEvent: EventRecordPtr;
    {$IFC NOT GENERATINGCFM}
    INLINE $70F6, $AAF2;
    {$ENDC}

    { For Extensions Strip 1.2 and later.                                    }
    { Check for gestalt features bit 'gestaltHasSBResolveAliasFile'.        }

    { resolves a chain of alias files just like the toolbox routine ResolveAliasFile()    }
    { but with an option to override the mounting of remote volumes.  Most of the code    }
    { is from an Apple snippet in the Technote "Quietly Resolving Finder Aliases".        }
    {}
    { Also, in the event of the display of an AppleShare mounting dialog, if the        }
    { current process is not in front, then the front process will be set to the        }
    { current one.  Since Extensions Strip 1.2 and later can only be run as regular        }
    { applications, the use of this trap is almost always safe to display mount            }
    { dialogs.  You should, however, set the mounting of remote volumes to false        }
    { if called inside a drop handler when the current process is not the front one.    }
    {}        { May move memory! }
FUNCTION SBResolveAliasFileMountOption(VAR fileFSSpec: FSSpec; resolveAliasChains: Boolean; VAR targetIsFolder: Boolean; VAR wasAliased: Boolean; mountRemoteVols: Boolean): OSErr;
    {$IFC NOT GENERATINGCFM}
    INLINE $70F5, $AAF2;
    {$ENDC}


{$ALIGN RESET}
{$POP}

{$SETC UsingIncludes := ExtensionsStripIncludes}

{$ENDC} {__EXTENSIONSSTRIP__}

{$IFC NOT UsingIncludes}
 END.
{$ENDC}